All Databases Inside Mac - Basic Toolbox

NewGWorld

High level routine to create an offscreen graphics world

#include <QDOff screen.h> Graphics Devices

QDErr NewGWorld( off screenGWorld, pixelDepth, boundsRect, cTable,

aGDevice, flags );

GWorldPtr *off screenGWorld ; A pointer to a CGrafPort record structure

short pixelDepth ; Pixel resolution of offscreen graphics world

Rect *boundsRect ; Determines offscreen pixel map's size and

coordinate system

CTabHandle cTable ; Handle to the color table to be used (use 0 for

default color table)

GDHandle aGDevice ; Used when the noNewDevice flag is set

GWorldFlags flags ;

returns an Error Code, 0 if no error

NewGWorld creates a graphics world: it allocates an offscreen port and pixel

map and its associated offscreen memory. It also allocates a new off screen

graphics device record unless you have specified that an existing graphics

device record be used - either one you supply or the one having the deepest

pixel depth in the rectangle defined by the boundsRect parameter.

NewGWorld initializes the offscreen port by calling OpenCPort. It sets the

port's visRgn field to a rectangular region coincident with its port rectangle.

NewGWorld initializes the offscreen device according to the parameters you

pass to it. NewGWorld generates an inverse table with the Color Manager

procedure MakeITable, unless one of the screen devices has the same color

table as the offscreen device, in which case it copies the inverse table from

that device.

You can compute the size of the offscreen memory buffer using this formula:

rowBytes * (boundsRect.bottom - boundsRect.top)

The actual address of the offscreen buffer is not directly accessible from the

pixel map. If you need access to the pixels without going through QuickDraw,

call GetPixBaseAddr to get a pointer to the pixels.

off screenGWorld Ptr to the offscreen graphics world

pixelDepth Determines the pixel resolution of the offscreen world. Possible

depths are 0,1,2,4,8,16 and 32 bits per pixel.

boundsRect Determines the offscreen pixel map's size and coordinate system,

and it becomes the offscreen port's portRect value, the off screen

pixel map's bounds, and the offscreen device's gdRect value. It is used

to determine the pixel map's rowBytes value and the size necessary

for allocating the offscreen buffer.

cTable A handle to the color table to be used. NewGWorld makes a copy of

that color table and puts its reference in the offscreen pixel map. It

is your application's responsibility to make sure that cTable

specifies a valid color table for th pixel depth. If cTable is NULL, the

default color table for the pixel depth is used.

aGDevice Used to create the offscreen graphics world when the noNewDevice

flag is set.

flags The flags can be a combination of pixPurge, noNewDevice, keepLocal

and useTempMem.

Returns: an Error Code. It is one of:

noErr (0) No error

paramErr (-50) Illegal parameter

cDepthErr (-157) Invalid pixel resolution

Notes: The flags field provides some options to your application. If you set the

pixPurge flag, NewGWorld makes the offscreen buffer a purgeable block.

Before drawing to or from the offscreen graphics world, your application

should call the LockPixels function and ensure that it returns TRUE. If

LockPixels returns FALSE, the offscreen buffer has been purged, and

your application should either call UpdateGWorld to reallocate it or draw

directly in the window it represents. Never draw to a purged off screen

buffer.

If you set noNewDevice, NewGWorld does not create a new off screen

device, and the depth and color table of the aGDevice parameter are used to

create the offscreen graphics world. If you set pixelDepth to 0, the deepest

device intersecting the boundsRect rectangle is used.

NewGWorld keeps a reference to whichever device it uses in the

offscreen graphics world data structure, and the SetGWorld procedure

uses that device to set the current device

Note that, to use a custom color table in an offscreen graphics world, you

need to create the associated offscreen device, because Color QuickDraw

needs the device's inverse table to draw.

If you set the keepLocal flag, your offscreen graphics environment is kept

in Macintosh main memory and is not cached to a graphics accelerator card.

Use this flag carefully, as it gives up the advantages of a graphics

acceleration card, if present.

If you set the useTempMem flag, NewGWorld allocates pixels in

temporary memory. You should use temorary memory only for fleeting

purposes, and only in conjunction with the AllowPurgePixels procedure

so that other applications can launch.

Referenced by (25):